Skip to content

Add durable external-action settlement protocol - #704

Merged
flyingrobots merged 17 commits into
mainfrom
task/694-durable-external-actions
Jul 29, 2026
Merged

Add durable external-action settlement protocol#704
flyingrobots merged 17 commits into
mainfrom
task/694-durable-external-actions

Conversation

@flyingrobots

@flyingrobots flyingrobots commented Jul 29, 2026

Copy link
Copy Markdown
Owner

Records typed external-action requests before adapter execution and admitted settlements before deterministic resumption.

Closes #694.

Summary by CodeRabbit

  • New Features

    • Added durable external-action processing with request, claim, and settlement lifecycle tracking.
    • Added deterministic recovery and replay that preserves settlements without repeating external effects.
    • Added validation for authorization, evidence, budgets, duplicate outcomes, and malformed settlements.
    • Added support for terminal outcomes including success, rejection, failure, and unknown results.
  • Documentation

    • Added the accepted durable external-action settlement architecture decision and updated related runtime, WAL, and security guidance.
  • Tests

    • Added comprehensive coverage for lifecycle ordering, authorization, recovery, replay safety, failures, and deterministic behavior.

@flyingrobots

Copy link
Copy Markdown
Owner Author

@coderabbitai review

@flyingrobots

Copy link
Copy Markdown
Owner Author

@codex please review

@coderabbitai

coderabbitai Bot commented Jul 29, 2026

Copy link
Copy Markdown
Contributor
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai

coderabbitai Bot commented Jul 29, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Warning

Review limit reached

@flyingrobots, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 15 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 227f4cc7-5279-4511-b230-a6866d13917f

📥 Commits

Reviewing files that changed from the base of the PR and between c4ee2d9 and b36bb20.

📒 Files selected for processing (12)
  • .ban-nondeterminism-allowlist
  • CHANGELOG.md
  • crates/warp-core/src/causal_wal.rs
  • crates/warp-core/src/external_action.rs
  • crates/warp-core/src/trusted_runtime_host.rs
  • crates/warp-core/tests/external_action_protocol_tests.rs
  • docs/adr/0026-durable-external-action-settlement.md
  • docs/architecture/application-contract-hosting.md
  • docs/topics/RuntimeAuthority.md
  • docs/topics/WAL.md
  • docs/topics/security/AuthorityBoundaries.md
  • tests/docs/test_adr_namespace.sh
📝 Walkthrough

Walkthrough

Echo adds a domain-neutral external-action protocol with canonical requests, WAL-backed claims and settlements, strict validation, Merkle-indexed recovery, replay-safe settlement handling, comprehensive tests, and ADR/runtime documentation.

Changes

External-action lifecycle

Layer / File(s) Summary
WAL transaction and frontier contracts
crates/warp-core/src/causal_wal.rs, crates/warp-core/src/evidence.rs
Adds external-action authorities, transaction and record kinds, stable codes, frontier validation, and test transaction-shape support.
Request, authorization, and settlement contracts
crates/warp-core/src/external_action.rs, crates/warp-core/src/lib.rs
Defines canonical request identities, adapter authorization, claims, settlement validation, protocol errors, payload decoding, and public module exports.
Admission and recovery flow
crates/warp-core/src/external_action.rs
Commits requests, claims, and settlements through WAL, validates bindings and budgets, and reconstructs lifecycle posture with Merkle frontier verification.
Lifecycle and failure validation
crates/warp-core/tests/external_action_protocol_tests.rs
Tests ordering, rejection paths, recovery states, replay behavior, determinism, duplicate settlements, commit failures, malformed payloads, and stable codes.
ADR and runtime documentation
CHANGELOG.md, docs/adr/*, docs/README.md, docs/architecture/*, docs/topics/*
Documents ADR 0026, authority boundaries, WAL lifecycle rules, recovery postures, replay semantics, and related indexes.

Estimated code review effort: 5 (Critical) | ~120 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Edict
  participant Echo
  participant Adapter
  participant WAL
  Edict->>Echo: Construct canonical external-action request
  Echo->>WAL: Commit REQUESTED record
  Echo->>Adapter: Issue request-bound claim
  Adapter->>Echo: Submit typed settlement candidate
  Echo->>WAL: Commit SETTLED record
  Echo-->>Edict: Resume from committed settlement bytes
Loading

Possibly related PRs

  • flyingrobots/echo#683: Extends related WAL transaction, record, and affected-frontier validation patterns for executable operations.

Suggested labels: release:echo-1.0

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed Concise and specific; it matches the new durable external-action settlement protocol.
Linked Issues check ✅ Passed Implements the request/claim/settlement WAL flow, recovery, replay, ADR, and fail-closed checks required by #694.
Out of Scope Changes check ✅ Passed Changes are tightly centered on the external-action protocol, tests, and supporting docs with no clear unrelated additions.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
✨ Finishing Touches 💡 1
🛠️ Fix failing CI checks 💡
  • Fix failing CI checks
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch task/694-durable-external-actions

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 6

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/warp-core/src/causal_wal.rs`:
- Around line 9626-9640: Centralize external-action transaction-kind to
record-kind mapping in a shared WalTransactionKind accessor, such as
external_action_record_kind() -> Option<WalRecordKind>. In
crates/warp-core/src/causal_wal.rs:9626-9640, update
validate_transaction_semantics to use the accessor while preserving the
exactly-one-frame validation. In
crates/warp-core/src/external_action.rs:1446-1470, replace
external_action_frame’s local expected match with the same accessor so both
validation paths share one lifecycle mapping.

In `@crates/warp-core/src/external_action.rs`:
- Around line 772-794: The Merkle mutation path currently traverses the same
256-level path twice, in root_digest_with_entry and refresh_merkle_path.
Collapse these operations into one traversal that computes each parent hash,
applies the corresponding node writes, and returns the resulting root; update
callers to use that combined result while preserving existing depth, sibling,
and empty-hash behavior.
- Around line 1432-1444: Change record_external_action_request,
claim_external_action, and admit_external_action_settlement to accept and mutate
a caller-owned RecoveredExternalActionIndexV1, advancing it only after each
successful commit instead of invoking full WAL replay. Retain
recover_external_action_index_from_store and its recover_from_frames_and_commits
path exclusively for cold recovery and initial index construction, avoiding
repeated payload decoding, allocations, and Merkle rebuilding on the kernel
request path.

In `@crates/warp-core/tests/external_action_protocol_tests.rs`:
- Around line 310-323: Replace the broad is_err() assertions in
external_action_protocol_tests.rs at lines 310-323, 338-351, 375-385, and
411-411 with exact Err(...) equality checks. At 310-323 assert the
request/authorization binding error; at 338-351 assert the
missing-lease-evidence variant; at 375-385 assert
ExternalActionProtocolErrorV1::MissingExternalEvidence; and at 411-411 assert
the frontier-mismatch variant, preserving each test’s existing setup.
- Around line 527-548: The current test only verifies invalid attempt ordinal
handling, not prevention of multiple claims for one request. Extend the relevant
external-action protocol test to record a request, perform an ordinal-0 claim
successfully, then submit a second ordinal-0 claim using a fresh lease digest;
assert the specific single-claim obstruction error and verify the store commit
count remains unchanged after the rejected claim.
- Around line 899-966: Update CommitFailingStore::flush_commit to determine the
current commit count without cloning the full commit vector. Use an existing
WalStorePort or InMemoryWalStore count/length accessor if available, preserving
the fail_on_commit_ordinal comparison and normal commit behavior.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: f7c29737-3f88-485d-b8e9-67f463ca1f9b

📥 Commits

Reviewing files that changed from the base of the PR and between c03061b and c4ee2d9.

📒 Files selected for processing (13)
  • CHANGELOG.md
  • crates/warp-core/src/causal_wal.rs
  • crates/warp-core/src/evidence.rs
  • crates/warp-core/src/external_action.rs
  • crates/warp-core/src/lib.rs
  • crates/warp-core/tests/external_action_protocol_tests.rs
  • docs/README.md
  • docs/adr/0026-durable-external-action-settlement.md
  • docs/adr/README.md
  • docs/architecture/application-contract-hosting.md
  • docs/topics/RuntimeAuthority.md
  • docs/topics/WAL.md
  • docs/topics/security/AuthorityBoundaries.md

Comment thread crates/warp-core/src/causal_wal.rs Outdated
Comment thread crates/warp-core/src/external_action.rs Outdated
Comment thread crates/warp-core/src/external_action.rs Outdated
Comment thread crates/warp-core/tests/external_action_protocol_tests.rs Outdated
Comment thread crates/warp-core/tests/external_action_protocol_tests.rs
Comment thread crates/warp-core/tests/external_action_protocol_tests.rs

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c4ee2d9b6d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread crates/warp-core/src/external_action.rs
Comment thread crates/warp-core/src/causal_wal.rs
Comment thread crates/warp-core/src/external_action.rs Outdated
Comment thread crates/warp-core/src/external_action.rs Outdated
Comment thread crates/warp-core/src/external_action.rs Outdated
Comment thread crates/warp-core/src/external_action.rs Outdated
@flyingrobots

Copy link
Copy Markdown
Owner Author

Merge gate: 40/40 checks pass at b36bb20; 0/12 review threads remain unresolved; the Code Lawyer pass fixed every admitted finding; focused and feature-complete local suites, clippy, formatting, determinism, and hook gates pass. Solo-maintainer substitution applies because no protected human-review requirement can be satisfied by a second collaborator.

@flyingrobots
flyingrobots merged commit 5413f55 into main Jul 29, 2026
40 checks passed
@flyingrobots
flyingrobots deleted the task/694-durable-external-actions branch July 29, 2026 22:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Specify durable external-action request and settlement protocol

1 participant